docs: draft MySQL snapshot parallelism page - #38091

Since we don't parallelize everything (sql server), I would make it more "can" and separate out. I think something like (?):

Materialize can parallelize snapshotting across the workers of the cluster
hosting the source. 

- **PostgreSQL sources** are parallelized by table, i.e., different tables are
  read concurrently by different workers. On PostgreSQL 14 and later,
  Materialize additionally attempts to partition each table's read across
  workers; tables that cannot be partitioned fall back to a single worker.

- **MySQL sources** are parallelized by table, i.e., different tables are read
  concurrently by different workers. For tables that meet [certain
  requirements](/ingest-data/mysql/snapshot-parallelism/), Materialize
  additionally partitions the table's read across workers. See [MySQL snapshot
  parallelism](/ingest-data/mysql/snapshot-parallelism/).

- **Kafka sources** are parallelized by topic partition, with partitions distributed
across workers.  Parallelism is bounded by the topic's partition count. 

- **SQL Server sources** are not parallelized; a single worker reads all tables.

I might have misinterpreted something ... but, hopefully, the above can give a gist of what I'm thinking

Adopted your structure, thanks. Only tweak: split the PG bullet's fallback clause into its own sentence.

?

The degree of snapshot parallelism depends on the number of workers. A cluster's
[size](/sql/create-cluster/#available-sizes) determines its number of workers,
so a larger cluster shortens the snapshot. The volume read from the upstream
database is unchanged; it is compressed into a shorter window of more concurrent
queries and connections. To determine whether snapshotting is overloading the
upstream database, and for ways to mitigate the load, see [Is the upstream
database
overloaded?](/ingest-data/troubleshooting/#is-the-upstream-database-overloaded).

Adopted.

? Is it more?

- **Read load.** Snapshotting puts read, CPU, and network load on the upstream
  system. The total load is proportional to the volume of data being
  snapshotted, while the [source cluster's parallelism](#parallelism) affects
  the peak load: more workers compress the reads into a shorter window.

?

Adopted the total-vs-peak framing.

The snapshotting sentence isn't true/applicable for kafka and sql server, yes?

Right. Scoped the bullet to PostgreSQL and MySQL sources.

?

Materialize splits the snapshot of an individual table across workers when all of the following conditions are met:

Adopted.

Could we simplify and add a link to the boundary sampling?

If a table does not meet these requirements, or if the boundary sampling fails,
its snapshot is not split: a single worker reads the table in full.

Adopted, with one extra sentence noting that different tables are still read concurrently.

an eligible table and maybe separate with a little tweak?

Materialize partitions an eligible table using the
leading characters of its primary key values. Before reading the table,
Materialize probes the primary key index to discover key prefixes and uses the
MySQL optimizer's row estimates to gauge how many rows fall under each prefix.
It extends the prefixes as needed to find boundaries that divide the table into
roughly even ranges. The probes are inexpensive point lookups, capped in
proportion to the table's estimated size, so the sampling phase stays negligible
next to the snapshot itself.

Each worker then reads only its assigned range, within the same
consistent snapshot of the upstream database, so the result is identical to a
single-worker snapshot, only faster.

Adopted your two-paragraph version.

Should these go into the https://github.com/MaterializeInc/materialize/blob/main/doc/user/content/headless/mysql-considerations-body.md ?

I'd keep these here for now: both bullets only apply when parallel snapshotting is active, which is private preview and flag-off, so they'd be noise in the general MySQL considerations. Worth revisiting when the feature is on by default.